.TH qthread_syncvar_readFE 3 "APRIL 2011" libqthread "libqthread"
.SH NAME
.B qthread_syncvar_readFE
\- waits for the syncvar to be full, then copies its data and empties it
.SH SYNOPSIS
.B #include <qthread.h>

.I int
.br
.B qthread_syncvar_readFE
.RI "(uint64_t * restrict " dest ", syncvar_t * restrict " src );
.SH DESCRIPTION
This function waits for memory to become full, and then empties it. When memory
becomes full, only one thread blocked like this will be awoken. Data is read
from
.I src
and stored in
.IR dest .
The
.I dest
may be NULL, in which case the data will not be copied.
.PP
The semantics of readFE are:
.RS
.PP
1 -
.IR src 's
FEB state must be "full"
.br
2 - data is copied from
.I src
to
.I dest
.br
3 -
.IR src 's
FEB state gets changed from "full" to "empty"
.RE
.SH RETURN VALUE
On success, the memory address
.I src
is marked empty, the memory address
.I dest
is filled with the contents of
.I src
and 0
.RI ( QTHREAD_SUCCESS )
is returned. On error, a non-zero error code is returned.
.SH ERRORS
.TP 12
.B ENOMEM
Not enough memory could be allocated for bookkeeping structures.
.B QTHREAD_TIMEOUT
Could not obtain the lock on the syncvar_t's status bits. This may be caused by
many things, including memory corruption, invalid syncvar, or even absurdly
excessive contention (because its protected by a naive spinlock rather than a
fair spinlock).
.SH SEE ALSO
.BR qthread_syncvar_empty (3),
.BR qthread_syncvar_fill (3),
.BR qthread_syncvar_writeFE (3),
.BR qthread_syncvar_writeF (3),
.BR qthread_syncvar_readFF (3),
.BR qthread_syncvar_status (3)
